package com.zenithmind.document.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.document.pojo.domain.DocumentPermission;
import com.zenithmind.document.pojo.dto.DocumentPermissionCreateDTO;
import com.zenithmind.document.pojo.dto.DocumentPermissionUpdateDTO;
import com.zenithmind.document.pojo.query.DocumentPermissionQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentPermissionVO;

import java.util.List;

/**
 * 文档权限服务接口
 * 遵循接口隔离原则：专注于权限管理功能
 * 遵循单一职责原则：只负责权限相关操作
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentPermissionService extends IService<DocumentPermission> {

    /**
     * 创建权限
     * 
     * @param createDTO 权限信息
     * @return 权限记录
     */
    DocumentPermissionVO createPermission(DocumentPermissionCreateDTO createDTO);

    /**
     * 更新权限
     * 
     * @param id 权限ID
     * @param updateDTO 更新信息
     * @return 是否成功
     */
    Boolean updatePermission(String id, DocumentPermissionUpdateDTO updateDTO);

    /**
     * 删除权限
     * 
     * @param id 权限ID
     * @return 是否成功
     */
    Boolean deletePermission(String id);

    /**
     * 批量删除权限
     * 
     * @param ids 权限ID列表
     * @return 是否成功
     */
    Boolean batchDeletePermissions(List<String> ids);

    /**
     * 分页查询权限
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentPermissionVO> getPermissionPage(DocumentPermissionQueryDTO queryDTO);

    /**
     * 获取权限详情
     * 
     * @param id 权限ID
     * @return 权限详情
     */
    DocumentPermissionVO getPermissionDetail(String id);

    /**
     * 获取文档权限列表
     * 
     * @param documentId 文档ID
     * @return 权限列表
     */
    List<DocumentPermissionVO> getDocumentPermissions(String documentId);

    /**
     * 获取用户权限列表
     * 
     * @param userId 用户ID
     * @return 权限列表
     */
    List<DocumentPermissionVO> getUserPermissions(String userId);

    /**
     * 检查用户权限
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param permission 权限类型
     * @return 是否有权限
     */
    Boolean checkUserPermission(String documentId, String userId, String permission);

    /**
     * 检查角色权限
     * 
     * @param documentId 文档ID
     * @param roleId 角色ID
     * @param permission 权限类型
     * @return 是否有权限
     */
    Boolean checkRolePermission(String documentId, String roleId, String permission);

    /**
     * 授予用户权限
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param permissions 权限列表
     * @param grantorId 授权人ID
     * @return 是否成功
     */
    Boolean grantUserPermissions(String documentId, String userId, List<String> permissions, String grantorId);

    /**
     * 撤销用户权限
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param permissions 权限列表
     * @return 是否成功
     */
    Boolean revokeUserPermissions(String documentId, String userId, List<String> permissions);

    /**
     * 授予角色权限
     * 
     * @param documentId 文档ID
     * @param roleId 角色ID
     * @param permissions 权限列表
     * @param grantorId 授权人ID
     * @return 是否成功
     */
    Boolean grantRolePermissions(String documentId, String roleId, List<String> permissions, String grantorId);

    /**
     * 撤销角色权限
     * 
     * @param documentId 文档ID
     * @param roleId 角色ID
     * @param permissions 权限列表
     * @return 是否成功
     */
    Boolean revokeRolePermissions(String documentId, String roleId, List<String> permissions);

    /**
     * 复制权限
     * 
     * @param sourceDocumentId 源文档ID
     * @param targetDocumentId 目标文档ID
     * @return 是否成功
     */
    Boolean copyPermissions(String sourceDocumentId, String targetDocumentId);

    /**
     * 继承权限
     * 
     * @param parentDocumentId 父文档ID
     * @param childDocumentId 子文档ID
     * @return 是否成功
     */
    Boolean inheritPermissions(String parentDocumentId, String childDocumentId);

    /**
     * 设置默认权限
     * 
     * @param documentId 文档ID
     * @param permissions 权限配置
     * @return 是否成功
     */
    Boolean setDefaultPermissions(String documentId, Object permissions);

    /**
     * 获取有效权限
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 有效权限列表
     */
    List<String> getEffectivePermissions(String documentId, String userId);

    /**
     * 获取权限树
     * 
     * @param documentId 文档ID
     * @return 权限树
     */
    Object getPermissionTree(String documentId);

    /**
     * 批量设置权限
     * 
     * @param documentIds 文档ID列表
     * @param permissions 权限配置
     * @return 是否成功
     */
    Boolean batchSetPermissions(List<String> documentIds, Object permissions);

    /**
     * 清理过期权限
     * 
     * @return 清理数量
     */
    Integer cleanupExpiredPermissions();

    /**
     * 权限审计
     * 
     * @param documentId 文档ID
     * @return 审计结果
     */
    Object auditPermissions(String documentId);

    /**
     * 获取权限变更历史
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 变更历史
     */
    List<Object> getPermissionChangeHistory(String documentId, Integer limit);

    /**
     * 导出权限配置
     * 
     * @param documentId 文档ID
     * @return 权限配置
     */
    Object exportPermissionConfig(String documentId);

    /**
     * 导入权限配置
     * 
     * @param documentId 文档ID
     * @param config 权限配置
     * @return 是否成功
     */
    Boolean importPermissionConfig(String documentId, Object config);

    /**
     * 验证权限配置
     * 
     * @param config 权限配置
     * @return 验证结果
     */
    Object validatePermissionConfig(Object config);

    /**
     * 获取权限模板
     * 
     * @return 权限模板列表
     */
    List<Object> getPermissionTemplates();

    /**
     * 应用权限模板
     * 
     * @param documentId 文档ID
     * @param templateId 模板ID
     * @return 是否成功
     */
    Boolean applyPermissionTemplate(String documentId, String templateId);

    /**
     * 创建权限模板
     * 
     * @param name 模板名称
     * @param config 权限配置
     * @return 模板ID
     */
    String createPermissionTemplate(String name, Object config);

    /**
     * 获取权限统计
     * 
     * @param documentId 文档ID
     * @return 统计信息
     */
    Object getPermissionStatistics(String documentId);

    /**
     * 同步权限
     * 
     * @param documentId 文档ID
     * @return 是否成功
     */
    Boolean syncPermissions(String documentId);
}
